<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libyubihsm: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">libyubihsm
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">libyubihsm Documentation</div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="Introduction"></a>
Introduction</h1>
<p>Libyubihsm is a library for communicating with a YubiHSM 2 device.</p>
<h1><a class="anchor" id="Usage"></a>
Usage</h1>
<p>To use the library, include &lt;<a class="el" href="yubihsm_8h.html" title="Everything you need to establish a connection to the YubiHSM 2 and use its functions. ">yubihsm.h</a>&gt; in the C code and pass the -lyubihsm flag to the linker. Debug output is controlled with the function <a class="el" href="yubihsm_8h.html#a24c3146e51242256af505961e763f417" title="Set verbosity level when executing commands. ">yh_set_verbosity()</a>.</p>
<p>First step of using a YubiHSM 2 is to initialize the library with <a class="el" href="yubihsm_8h.html#a5392844a98c6220c69fe08d3dcf8f1bc" title="Global library initialization. ">yh_init()</a>, initialize a connector with <a class="el" href="yubihsm_8h.html#a9c700747902a722d6c1d2073277de294" title="Instantiate a new connector. ">yh_init_connector()</a> and then connect it to the YubiHSM 2 with <a class="el" href="yubihsm_8h.html#aa19be6ac70a2a5d1cef8d7e6902fe05f" title="Connect to the device through the specified connector. ">yh_connect()</a>. After this, a session must be established with <a class="el" href="yubihsm_8h.html#a4e5534e6c597a7d32040ea1cc7254c93" title="Create a session that uses an encryption key and a MAC key derived from a password. ">yh_create_session_derived()</a>, <a class="el" href="yubihsm_8h.html#ac1534725e97dbf81b37652fe1bffb97a" title="Create a session that uses the specified encryption key and MAC key to derive session-specific keys...">yh_create_session()</a> or <a class="el" href="yubihsm_8h.html#a296b43eadb1151017ba8e9578b351c5e" title="Begin creating an external session. ">yh_begin_create_session_ext()</a>. The session must then be authenticated using <a class="el" href="yubihsm_8h.html#a77870209747d5ccd90f9da3aae2bdfa8" title="Authenticate session. ">yh_authenticate_session()</a>.</p>
<p>When a session is authenticated, commands can be exchanged over it. The functions in the namespace yh_util are high-level convenience functions that do specific tasks with the device.</p>
<h1><a class="anchor" id="api"></a>
API Reference</h1>
<p>All public functions and definitions can be found in <a class="el" href="yubihsm_8h.html" title="Everything you need to establish a connection to the YubiHSM 2 and use its functions. ">yubihsm.h</a></p>
<h1><a class="anchor" id="example"></a>
Code example</h1>
<p>Here is a small example of establishing a session with a YubiHSM 2 and fetching some pseudo random bytes before closing the session.</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">void</span>) {</div><div class="line">  <a class="code" href="yubihsm_8h.html#a114f98fee4b67eadd9b89b675632c710">yh_connector</a> *connector = NULL;</div><div class="line">  <a class="code" href="yubihsm_8h.html#aa3420d8ccc1fb0b0dee1af5a53cc79de">yh_session</a> *session = NULL;</div><div class="line">  uint8_t data[128] = {0};</div><div class="line">  <span class="keywordtype">size_t</span> data_len = <span class="keyword">sizeof</span>(data);</div><div class="line"></div><div class="line">  assert(<a class="code" href="yubihsm_8h.html#a5392844a98c6220c69fe08d3dcf8f1bc">yh_init</a>() == <a class="code" href="yubihsm_8h.html#ae4f602d2343d01b1727dfd633169d366a405155512dc2284dc210ed15be1d0815">YHR_SUCCESS</a>);</div><div class="line">  assert(<a class="code" href="yubihsm_8h.html#a9c700747902a722d6c1d2073277de294">yh_init_connector</a>(<span class="stringliteral">&quot;http://localhost:12345&quot;</span>, &amp;connector)==<a class="code" href="yubihsm_8h.html#ae4f602d2343d01b1727dfd633169d366a405155512dc2284dc210ed15be1d0815">YHR_SUCCESS</a>);</div><div class="line">  assert(<a class="code" href="yubihsm_8h.html#aa19be6ac70a2a5d1cef8d7e6902fe05f">yh_connect</a>(connector, 0) == <a class="code" href="yubihsm_8h.html#ae4f602d2343d01b1727dfd633169d366a405155512dc2284dc210ed15be1d0815">YHR_SUCCESS</a>);</div><div class="line">  assert(<a class="code" href="yubihsm_8h.html#a4e5534e6c597a7d32040ea1cc7254c93">yh_create_session_derived</a>(connector, 1, <a class="code" href="yubihsm_8h.html#ac850296655b387c6fd54492144507de1">YH_DEFAULT_PASSWORD</a>,</div><div class="line">  strlen(<a class="code" href="yubihsm_8h.html#ac850296655b387c6fd54492144507de1">YH_DEFAULT_PASSWORD</a>), <span class="keyword">false</span>, &amp;session) == <a class="code" href="yubihsm_8h.html#ae4f602d2343d01b1727dfd633169d366a405155512dc2284dc210ed15be1d0815">YHR_SUCCESS</a>);</div><div class="line">  assert(<a class="code" href="yubihsm_8h.html#a77870209747d5ccd90f9da3aae2bdfa8">yh_authenticate_session</a>(session) == <a class="code" href="yubihsm_8h.html#ae4f602d2343d01b1727dfd633169d366a405155512dc2284dc210ed15be1d0815">YHR_SUCCESS</a>);</div><div class="line">  assert(<a class="code" href="yubihsm_8h.html#af1bc8ed34687d83701eb3cc673ad4b96">yh_util_get_pseudo_random</a>(session, <span class="keyword">sizeof</span>(data), data,</div><div class="line">&amp;data_len)==<a class="code" href="yubihsm_8h.html#ae4f602d2343d01b1727dfd633169d366a405155512dc2284dc210ed15be1d0815">YHR_SUCCESS</a>);</div><div class="line">  assert(data_len == <span class="keyword">sizeof</span>(data));</div><div class="line">  assert(<a class="code" href="yubihsm_8h.html#a61ab8dbab67b1cceb49cd306f8c3f4b1">yh_util_close_session</a>(session) == <a class="code" href="yubihsm_8h.html#ae4f602d2343d01b1727dfd633169d366a405155512dc2284dc210ed15be1d0815">YHR_SUCCESS</a>);</div><div class="line">  assert(<a class="code" href="yubihsm_8h.html#a1a35f8ae5a739848408633a514e41b2d">yh_destroy_session</a>(&amp;session) == <a class="code" href="yubihsm_8h.html#ae4f602d2343d01b1727dfd633169d366a405155512dc2284dc210ed15be1d0815">YHR_SUCCESS</a>);</div><div class="line">  assert(<a class="code" href="yubihsm_8h.html#ab12d5a42d2219741bd3630b99ed1c7d2">yh_disconnect</a>(connector) == <a class="code" href="yubihsm_8h.html#ae4f602d2343d01b1727dfd633169d366a405155512dc2284dc210ed15be1d0815">YHR_SUCCESS</a>);</div><div class="line">}</div></div><!-- fragment --> </div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>
